feat: polymorphic helper for request body streaming by tank-bohr · Pull Request #484 · elixir-mint/mint

tank-bohr · 2026-04-26T09:01:02Z

Continues the discussion from the #477

Before

defmodule MintHttpStreaming do
  @default_chunk_size 16_384

  def run(method, %URI{scheme: scheme} = uri, headers, body, opts)
      when scheme in ~w[http https] do
    scheme = String.to_existing_atom(scheme)
    port = uri.port || URI.default_port(uri.scheme)
    path = URI.to_string(%URI{uri | scheme: nil, host: nil, authority: nil})

    with {:ok, conn} <- Mint.HTTP.connect(scheme, uri.host, port, opts) do
      stream(conn, method, path, headers, body)
    end
  end

  defp stream(conn, method, path, headers, body) do
    with {:ok, conn, ref} <- Mint.HTTP.request(conn, method, path, headers, :stream) do
      stream_body(conn, ref, body)
    end
  end

  defp stream_body(conn, ref, "") do
    Mint.HTTP.stream_request_body(conn, ref, :eof)
  end

  defp stream_body(conn, ref, body) do
    chunk_size = min(chunk_size(conn, ref), byte_size(body))
    <<chunk::binary-size(chunk_size), rest::binary>> = body

    with {:ok, conn} <- Mint.HTTP.stream_request_body(conn, ref, chunk) do
      stream_body(conn, ref, rest)
    end
  end

  defp chunk_size(conn, ref) do
    case Mint.HTTP.protocol(conn) do
      :http1 ->
        @default_chunk_size

      :http2 ->
        chunk_size_http2(conn, ref)
    end
  end

  defp chunk_size_http2(conn, ref) do
    min(
      Mint.HTTP2.get_window_size(conn, :connection),
      Mint.HTTP2.get_window_size(conn, {:request, ref})
    )
  end
end

After

defmodule MintHttpStreaming do
  def run(method, %URI{scheme: scheme} = uri, headers, body, opts)
      when scheme in ~w[http https] do
    scheme = String.to_existing_atom(scheme)
    port = uri.port || URI.default_port(uri.scheme)
    path = URI.to_string(%URI{uri | scheme: nil, host: nil, authority: nil})

    with {:ok, conn} <- Mint.HTTP.connect(scheme, uri.host, port, opts) do
      stream(conn, method, path, headers, body)
    end
  end

  defp stream(conn, method, path, headers, body) do
    with {:ok, conn, ref} <- Mint.HTTP.request(conn, method, path, headers, :stream) do
      stream_body(conn, ref, body)
    end
  end

  defp stream_body(conn, ref, "") do
    Mint.HTTP.stream_request_body(conn, ref, :eof)
  end

  defp stream_body(conn, ref, body) do
    {chunk, rest} = Mint.HTTP.next_body_chunk(conn, ref, body)

    with {:ok, conn} <- Mint.HTTP.stream_request_body(conn, ref, chunk) do
      stream_body(conn, ref, rest)
    end
  end
end

Wins:

allows to keep stream_request_body/3 protocol-agnostic
provides convenient API for the most obvious and straightforward use-case
keeps the API a low-level and allow caller to have all the control

ericmj · 2026-04-26T10:03:18Z

You are treating H2 send window and sndbuf as two implementations of "how big should the next chunk be," but they're values from different layers that serve different purposes.

The H2 send window is a contract with the peer, if we exceed it we get a protocol error, Mint checks it because violating it is a wire-level bug, not for performance or to avoid blocking.

sndbuf is the size of the kernel send buffer. It's not a contract and no error if you "exceed" it. gen_tcp.send just blocks until the kernel drains enough bytes to accept more.

For H1, sndbuf is the buffer's total capacity, not its current free space (unlike H2 windows). Send one sndbuf-sized chunk and it sits in the kernel buffer until the receiver ACKs, if we send a second one immediately and it blocks waiting for ACKs. Chunking by sndbuf only sizes the first send to fit an empty buffer, every send after that depends on how fast ACKs come back.

For H2, the window can easily exceed sndbuf. When the window is bigger, sending up to it fills the kernel buffer and blocks anyway. The H2 code only guarantees protocol compliance, not non-blocking sends.

For these reasons the proposed implementation is a leaky abstraction over H1 and H2. With the change in #483 users can implement streaming and it's up to the user to pick a chunk size that's appropriate for their application's needs.

ericmj · 2026-04-26T11:53:00Z

To elaborate on this a bit more and suggest a hopefully acceptable solution.

The library should not pick the application chunk size. The user should pick a chunk size based on latency, memory, producer shape, backpressure model, and tolerance for blocking. Mint should only expose the protocol constraint.

Given that, we can add a function Mint.HTTP.request_body_window(conn, ref) :: :infinity | non_neg_integer(). This would be the upper limit of what a user is allowed to send, then a user should do:

user_chunk_size = 16_384

limit =
  case Mint.HTTP.request_body_window(conn, ref) do
    :infinity -> user_chunk_size
    window -> min(user_chunk_size, window)
  end

feat: polymorphic helper for request body streaming

a2a1dcc

tank-bohr force-pushed the next_body_chunk branch from 3b56627 to a2a1dcc Compare April 26, 2026 09:09

ericmj closed this Apr 26, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: polymorphic helper for request body streaming#484

feat: polymorphic helper for request body streaming#484
tank-bohr wants to merge 1 commit intoelixir-mint:mainfrom
tank-bohr:next_body_chunk

tank-bohr commented Apr 26, 2026

Uh oh!

ericmj commented Apr 26, 2026 •

edited

Loading

Uh oh!

ericmj commented Apr 26, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

tank-bohr commented Apr 26, 2026

Uh oh!

ericmj commented Apr 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ericmj commented Apr 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ericmj commented Apr 26, 2026 •

edited

Loading

ericmj commented Apr 26, 2026 •

edited

Loading